home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / falcon / programm.ing / nt_dsp1.lzh / NT_DSP1.MSA / FLOAT / FPCALLS.HLP < prev    next >
Text File  |  1989-01-24  |  12KB  |  290 lines
  1. 2 FPCALLS
  2.  
  3.  
  4.  FPLIB - MOTOROLA DSP56000/1 FLOATING POINT SOFTWARE SUBROUTINE LIBRARY
  5.  
  6.              CALLING CONVENTIONS - VERSION 2.0
  7.  
  8.  Revision 1.0      August 29, 1986
  9.  Revision 1.1      March  25, 1987
  10.  Revision 2.0      October 5, 1987
  11.  
  12.  MOTOROLA, INC.
  13.  COPYRIGHT 1986, 1987
  14.  ALL RIGHTS RESERVED
  15.  
  16.  INTRODUCTION
  17.  
  18.  FPLIB is a useful set of floating point arithmetic subroutines for the
  19.  Motorola DSP56000/1 digital signal processor.  This HELP file defines
  20.  the subroutine calling conventions and condition codes used by the
  21.  DSP56000/1 floating point software subroutine library (FPLIB).
  22.  Register usage and error conditions are described.  The storage format
  23.  and arithmetic representation are not discussed here but are given in
  24.  the FPDEF.HLP file. 
  25.  
  26.  FPLIB INITIALIZATION AND ASSUMPTIONS
  27.  
  28.  FPLIB must be initialized by calling the subroutine "FPINIT" before
  29.  any other FPLIB subroutines are used.  FPLIB assumes that R0, N0 and
  30.  M0 are RESERVED pointers for FPLIB and should not be used by the
  31.  calling program. FPLIB also assumes that the scaling modes are
  32.  DISABLED (NO SCALING) and that the CCR limit (L) bit is cleared so
  33.  that FPLIB subroutines can set it to indicate error conditions.  These
  34.  assumptions are initialized by the FPINIT subroutine.  FPINIT need
  35.  only be called once per application program unless the above
  36.  assumptions are violated.  However, FPINIT may be called at any time
  37.  if the user needs to restore the FPLIB assumptions. No FPLIB state
  38.  information (except the L bit error flag) is carried from one FPLIB
  39.  subroutine to another.  A final caution is that FPINIT clears the CCR
  40.  L bit so any previous error indication will be lost. 
  41.  
  42.  FPLIB MEMORY USAGE
  43.  
  44.  FPLIB uses approximately 32 words of data memory for storage of certain
  45.  constants and tables.  The user may specify any address in X or Y data
  46.  memory for this storage area.  This is done by specifying the memory
  47.  space label "fp_space" with an assembler DEFINE directive and the memory
  48.  base address label "fp_temp" with an assembler EQU directive as shown
  49.  below.
  50.  
  51.        define      fp_space      'x'      ;FPLIB storage in X Data RAM
  52.  fp_temp      equ      0                  ;beginning at address $0000
  53.  
  54.  For code efficiency, fp_temp should be located in the bottom 64 locations
  55.  of X or Y data memory to take advantage of the absolute short addressing
  56.  mode.
  57.  
  58.  The current version of FPLIB requires approximately 200 program memory
  59.  locations if all subroutines are included.  Most subroutines require
  60.  other subroutines to be included since many share common code.
  61.  
  62.  FPLIB REGISTER USAGE
  63.  
  64.  FPLIB uses all of the DSP56000/1 data ALU registers for input variables,
  65.  output variables and temporary storage.  FPLIB does not preserve any
  66.  data ALU registers so users should save/restore data ALU registers as
  67.  required.  Input and output variables are described using a floating
  68.  point register notation (shown in capital letters below) similar to the
  69.  DSP56000/1 register names.  The floating point and fixed point register
  70.  usage is indicated in lower case letters.  The floating point mantissa
  71.  word is indicated with "m" and the floating point exponent word is
  72.  indicated with "e".
  73.  
  74.  Input variables:
  75.  
  76.     X      x1 = mx  (normalized)
  77.            x0 = ex
  78.  
  79.     Y      y1 = my  (normalized)
  80.            y0 = ey
  81.  
  82.     A      a2 = sign extension of ma
  83.            a1 = ma  (normalized)
  84.            a0 = zero
  85.  
  86.            b2 = sign extension of ea (always zero)
  87.            b1 = ea
  88.            b0 = zero
  89.  
  90.     D       a = fixed point data
  91.  
  92.  Output variables:
  93.  
  94.     R      a2 = sign extension of mr
  95.            a1 = mr  (normalized)
  96.            a0 = zero
  97.  
  98.            b2 = sign extension of er (always zero)
  99.            b1 = er
  100.            b0 = zero
  101.  
  102.     D       a = fixed point data
  103.  
  104.  FPLIB SUBROUTINE CALLS
  105.  
  106.  FPLIB subroutines are called with a JScc, JSCLR, JSR or JSSET instruction.
  107.  Input variables are loaded before calling the FPLIB subroutine and output
  108.  variables are available after the FPLIB subroutine returns to the calling
  109.  program.  Input variables may be destroyed by the subroutine.  In general,
  110.  the condition codes are only valid after the floating point compare "fcmp"
  111.  subroutine.
  112.  
  113.  Entry Point      Operation
  114.  -----------      ---------
  115.  fpinit            Initialize FPLIB
  116.  fadd_xa           R = A + X
  117.  fadd_xy           R = Y + X
  118.  fsub_xa           R = A - X
  119.  fsub_xy           R = Y - X
  120.  fcmp_xa           A - X, set condition codes
  121.  fcmp_xy           Y - X, set condition codes
  122.  fmpy_xa           R = A * X
  123.  fmpy_xy           R = X * Y
  124.  fmac_xya          R = A + X * Y
  125.  fmac_mxya         R = A - X * Y
  126.  fdiv_xa           R = A / X
  127.  fdiv_xy           R = Y / X
  128.  fscal_xa          R = A * 2**ex, assumes mx=1
  129.  fscal_xy          R = Y * 2**ex, assumes mx=1
  130.  fsqrt_a           R = square root (A)
  131.  fsqrt_x           R = square root (X)
  132.  fneg_a            R = - A
  133.  fneg_x            R = - X
  134.  fabs_a            R = absolute value (A)
  135.  fabs_x            R = absolute value (X)
  136.  fix_a             D = fixed point conversion (A)
  137.  fix_x             D = fixed point conversion (X)
  138.  float_a           R = floating point conversion (A)
  139.  float_x           R = floating point conversion (X)
  140.  floor_a           R = floor(A), largest integer less than or equal to A
  141.  floor_x           R = floor(X)
  142.  fceil_a           R = ceil(A), smallest integer greater than or equal to A
  143.  fceil_x           R = ceil(X)
  144.  frac_a            R = frac(A), fractional part of A
  145.  frac_x            R = frac(X)
  146.                        
  147.  
  148.  FPLIB ERROR CONDITIONS
  149.  
  150.  The FPLIB subroutines detect various error conditions and set the CCR
  151.  limit (L) bit as an error flag.  The user may test the CCR L bit upon
  152.  return from the subroutine.  Note that the CCR L bit remains set until
  153.  cleared by the user.  To promote real-time application, each
  154.  subroutine also substitutes a floating point (or fixed point) value
  155.  for the result.  This allows the real-time system to run continuously
  156.  in the presence of errors which would typically abort a FORTRAN or C
  157.  program.  These error conditions and result values are given for each
  158.  subroutine below. 
  159.  
  160.  Entry Point    Error Conditions            Result Value
  161.  -----------    ----------------            ------------
  162.  fpinit         none
  163.  fcmp_xa      
  164.  fcmp_xy
  165.  float_a
  166.  float_x
  167.  floor_a
  168.  floor_x
  169.  fceil_a
  170.  fceil_x
  171.  frac_a
  172.  frac_x
  173.  
  174.  fadd_xa        floating point overflow     maximum value, correct sign.
  175.  fadd_xy        floating point underflow    zero.
  176.  fsub_xa
  177.  fsub_xy            
  178.  fmpy_xa
  179.  fmpy_xy
  180.  fmac_xya
  181.  fmac_mxya
  182.  fscal_xa
  183.  fscal_xy
  184.  fneg_a
  185.  fneg_x
  186.  fabs_a
  187.  fabs_x
  188.  
  189.  fdiv_xa        floating point overflow       maximum value, correct sign.
  190.  fdiv_xy        floating point underflow      zero.
  191.                 divide by zero                if dividend non-zero, maximum
  192.                                               value, correct sign.
  193.                                               if dividend zero, zero.
  194.  
  195.  fsqrt_a        negative input value          zero.
  196.  fsqrt_x
  197.  
  198.  fix_a          fixed point overflow          maximum fixed point value,
  199.  fix_x                                        correct sign.
  200.  
  201.  FPLIB CONDITION CODES
  202.  
  203.  In general, conditional jumps based on condition codes may be used
  204.  only after calling the floating point compare subroutines (fcmp_xa and
  205.  fcmp_xy).  The following branch conditions can be used after calling
  206.  fcmp_xa or fcmp_xy. Other branch conditions should not be used. 
  207.  
  208.        "cc" Mnemonic                  Condition
  209.        -------------                  ---------
  210.        EQ - equal                      Z = 1
  211.        GE - greater than or equal      N eor V = 0
  212.        GT - greater than               Z + (N eor V) = 0
  213.        LE - less than or equal         Z + (N eor V) = 1
  214.        LT - less than                  N eor V = 1
  215.        NE - not equal                  Z = 0
  216.  
  217.  FPLIB BUGS AND EXTENSIONS
  218.  
  219.  FLPIB has been tested for a short time and is thought to be bug free.
  220.  However, if bugs